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The power of UBand is in your own hands, enabling you to create interactive content like never before. With short development times, powerful features, and everything available free online from =
 
Getting your set up ready for writing Uband compatible content 

To start with make sure you've got a recent version of either netscape or microsoft explorer web browsers installed and working smoothly on your computer. The version should be at least 4.5, and preferably one released in 2000 or after, see your 'about' page for version/release information. Be sure to also enable Java and Javascript as well in it's preferences. You'll also need the latest Uband decoder for your platform. Get one at =. If you're downloading a new decoder or browser try out some of the online Uband content first at = , this might save you lots of headaches! 

 There's a good development pack that's been put together for users who are just starting out writing for U-Band. It contains a number of templates, examples and reference documents to help you. It's platform independent, and available at =. It's also available in other compressed formats and in un-zipped pieces at =.
 
 You can also add the debugging extension to your decoder, download the platform independant extension at =. Use this and the UBAND.DEBUG=ON statement in your content to enable verbose output in a secondary window on screen. You can turn the debugging on and off using this statement. The debug extension also enables hotkeys to stop content while it's running and for viewing of internal varibles. 

 An online web site is recommended to really test out your pages as off-line testing only goes so far with browsers espcially with the newer security considerations many have implemented. You'll find that some possible security exceptions are only shown up by online testing. An internet connection is also required at runtime if you're intending on using networked resources. Finally a good plain text editor, or your favorite word-pro set to ASCII/TXT filetype is as important as any of the above. 

 For more information on only development issues and nothing else, you may with to join the U-Band Developers email list. It's a short monthly emailing with information on updates, new features, help and any information relevant to content developers. You can join by sending an email to = with 'subscribe' as the subject. 

 There's also an online live Em Channel for developer chat providing a forum for the discussion of UBand development. Access it on =over your standard Em Channels connection. If you haven't already got an Em Channels connection, you can get one of those at =

primer
 
This primer is for anyone who would like to create content in Uband, but has either never programmed before or would like a full ground-up look inside the Uband language. 
What is the Uband language? 
In the same way that we all learn to express ourselves in our spoken language, so Uband is the language you use to communicate with Uband systems. Spoken languages are made up not only of component words, but also a number of grammatical rules which enable us to construct sentences that are meaningful to others. In the same way there are rules that govern how certain words in the Uband language are used to communicate your ideas. 

 We will now try writing something that Uband can understand and do for us.  Say we would like to display our name on the screen. You might think we could just type our name there. That's not as crazy as it might seem. But it would be meaningless in the same as as someone speaking there name to you and then walking away! Why you asked did they give you there name? So if they wanted you to tell someone else their name, you can't do that because you didn't know that's what they wanted. In other words there is no action to be taken when just being given information. Uband needs actions in the same way. Take a look below: 

Margot 

We'll be Margot for now. The first thing we'll need to do is to quote our name. We do this because Margot is something definate, something that we're typing in that is to be remembered just as it is. Like above when walking up to someone speaking your name, or in a news article, where such items are removed from the text by using quotes: 

"Margot" 

Now you've quoted something to Uband, it just needs to know what to do with it. Actions in Uband are called methods. There's a method to do just about anything, and a method for displaying something on the screen is print(): 

print("Margot") 

Those brackets come with the method, they say 'Do this action to everything that's inside these brackets'.  Secondly notice the action is on the left hand side. Print is saying to Uband, 'print on the screen what's about to follow'. And what follows is your quote, your name. 
That might work, but we just need to tell Uband we've finish with this line. A sentence ends with a period, while Uband's 'sentences' end with a semi-colon ';' . (The period is used for other things as we'll see later on) 

print("Margot"); 

That's it. You can replace Margot with your own name, or anything else, and it will be displayed. You may like to remove the quotes and enter some simple math such as : 

print(2+4); 

Uband adds up your numbers and displays the result 6. If you left the quotes on as in:
 
print("2+4"); 

Uband would see it as being quoted, and would display it as-is: '2+4'. 
 Leaving the quotes off of Margot wont work as Uband then sees Margot as refering to a store, or a variable. We'll learn about variables and how to use them next. In the meantime you might like to experiment with the print() method and using different arguments (what goes in-between the brackets). If you are unsure about how to type in your own content for Uband, read this for a 5 minute set up on most machines to get you started. 

Uband content type 
Uband material is always stored with the .uband or .ub (depreciated -for use on older systems) for content and .ube for uband decoder extensions.These file types should be assigned to be handled by your uband decoder software. Doing this will ensure that your content will run locally and from over the internet. 
 The content of a .uband file is either in plain text (ASCII) format, or an encoded version which always starts with the header line 'EMCHANNELS U-BAND:' followed by version information used by your decoder to interpret the file. You can use either format online, the plain text is better when you're in the process of developing your site, while the encoded type is smaller/faster to download but is one stage away from your source code. Please also note that encoding your code does not by default give it any protection, although some levels of security are available if you wish to enable them. 

Uband source files 
Writing Uband code is easy, all you need is a text editor or word processor that's capable of producing ASCII (.TXT file standard) output. 
Sample source file: 

# simpleinfo.tnx : Uband source file 
# 
# version 1.0 
# may 2001 
# 

// this program creates a new window and prints 
// some informtion in it 
new window newwin; 
newwin.width=400; 
newwin.height=200; 
newwin.title="source demo"; 
newwin.background("blue"); 
newwin.color("white"); 
printf("This version of Uband is %d.%d\n", system.versionmajor, system.versionminor); 
printf("It's release name is : %s\n", system.releasename); 
 
You'll see two style's of commenting, one using the hash '#" and the other the double forward slash '//'. There is no difference in the two, it is down to your preference as to which one you use and for what. We use the hash for header comments about the file in general, while using the double forward slash for comments about the commands and methods that follow. 

Uband source code should always be stored with the '.tnx' extension as it's last characters. This enables Uband to identify your code quickly both locally and when you transfer it online. The other extension is the precompiled object code, which is smaller and can be run faster. It has the extension '.txo' (T - X - and the letter O). Object code is the prefered format for online running where you're interested in providing the content to the user rather than a shared method etc.. 

You'll notice that each line ends with a semi-colon. Without it Uband will continue to read on to the next line as part of the same statement. The semi-colon tells Uband that you have completed this statement. If you wish you can continue a single statement over many lines, it does not have to stay in a single long sequence: 



# long printf over two lines 

printf("hello my name is %s from %s\n", 
user.name, 
user.location); 
 
If this helps the readability of your code then it's there for you to use. 

Dive In 

A fuller description of  writing U-Band content is given later and also in other more in-depth papers, but we're going to get straight to the code and look at a simple 'Hello World' program. 
init() 
{ 
UBAND.TITLE "Hello world!"; 
UBAND.AUTHOR.NAME "Charlote Greenwood"; 
UBAND.AUTHOR.LINK "www./go/charlote"; 
UBAND.COPYRIGHT "Copyright 2001 *some company here*";
 //‭ so hello world its the first program that most people are told
‭ // to write. so most do. my first printed charlote was skill all over
‭ // the screen. i was about 11 so there it is. and anyway it wasn't my
‭ // first, it was my first in public. a computer class.
‭ // I like long comments. Life like programs should be
‭ // commented and indented perfectly. but its not. at least i don't
‭ // think it is. thats not to say to others it is though.
‭ // hello world. version... lost count!
 
UBAND.LANGUAGE "ENGLISH"; 
UBAND.AUTHORIZE NULL; 
s._dispwidth=WINDOW.WIDTH; 
s._dispheight=WINDOW.HEIGHT; 
s._chrwidth=WINDOW.WIDTH.CHR; 
s._chrheight=WINDOW.HEIGHT.CHR; 
} 
start() 
{ 
cl(); 
_message="Hello World!"; 
box(0,0,_dispwidth,_dispthheight,15); 
ttpos(_chrheight/2,(_chrwidth/2)-strlen(_message),_message); 
getkey(); 
} 
exit() 
{ 
closewindow(); 
} 

	Get this program online

Your 'Hello World' is displayed in the center of a new U-Band window, nothing is really set for the display, defaults of the host decoder being relied on. You will notice the three main methods of the above program: init() is called first, then start(), and as the program ends so the statements in exit() are executed. Init() can contain anything, but is only called once so should contain variable and other set up methods. Only init() can contain global variables. Start() is called next and is the main program, in this case it uses the _chrheight etc. variables to position the output. 
 Variables that are defined in the program all begin with an underscore '_'. When initializing they can have extra pre-cursors which determine their scope and type. s._dispwidth is a 'Shared' type and is made available anywhere within the local program as _dispwidth. The type 'g.' would enable the variable to be shared globally, literary over the entire internet as any other program can call on its contents. 
 Internal methods are all pre loaded, you do not need to call upon any includes. Cl() clears the screen and takes an optional argument for the screens background color. If you leave out arguments such as this the user's local preferences are used. Be aware that if you rely on one default value to be careful in setting another. For example if we did a cl() and the user's background was white, then a following color(white) would make the text invisible. 

 Box() taking 5 arguments will draw a rectangle from x1,y1 to x2,y2 with a color. Many methods like box() can take different numbers of arguments which change the way they work. Adding another argument to box() will fill it with that color. 

 Ttpos() is a print output method which contains the co-ordinates as its first two arguments. The text cords are the text position (in character cells). Standard widths and heights for uband text windows are 40x25 and 80x25 but these can't be relied upon, so the variables _chrwidth and _chrheight were earlier set in init() and used to center the text. The ts() method prints a string without the position arguments. It's placement is determined by the previous ttpos() and will lead on from that position. Escape sequences such as \n and \r for newline and carriage return can be used with ttposf() and tsf() methods. 

 Getkey() in its default state waits for a single key press and then returns that key. You don't need to do anything with return values of methods if you don't wish to. A getkey() that uses the input would look something like: 

    _textin=""; 
    _textin=getkey(); 
    if (_textin[0]==' ') tsf("\nSPACE!\n\b"); 

 Use a single equals to assign values to a variable and a double equals when testing the stored value. Braces can be used for if's with multiple conditional methods. 

 Closewindow() tells the decoder that we've finished and shuts down the display. It's not actually required if exiting normally as it is called automatically when the exit() routine completes. Exit() is called when start() reaches its last method, or if you call is with 'exit()'. 
 The UBAND. settings at the beginning of the program are all optional. They firstly set up information that's used by the decoder and some online services to classify your content. Finally they can set preferences as to who has access to your content, and to what extent. It is good practice to set at least these given in the demonstration program. 
  
More to come 

 UBand features portability, ease of creation, and capabilities for interactive content. You'll find that in a matter of moments you can be on the way to creating exciting online content thats free and globally available. Easy to access features such as multi aspect scrolling, dynamic zooming, and distributed methods make for a wide palette for your creative imagination. You can let everyone see your content for free too by adding your own channel to the Em Channels network. Once your channel is completed go to www to be a part of the EmC network! 


Variable assignments
 
You can be very casual or precise about defining how your data is stored, in the most simplest 
cases can be something such as: 
_text="hello there"; 
can be used. Where a new variable named _text is set up (or one that already exists is referenced) and it is used to store the portable string "hello there". This method of defining variables works fine, but no variable is 'fixed' as a certain type. So after intia;izing _text with our greetings string you could then write: 
_text=100; 
 which would change its first implied declaration as a string, to become an integer of value 100. That's fine if it's what you wanted to do, but if you didn't, it wouldn't be caught as being 'wrong'. By declaring _text as a string when you initialize it, you could not then change it's format in such a wholly implied way. To declare or not to declare your variable types is down to your preference on how you work. A fully declared variable set can be easier to debug, and is self explanitory for anyone else who needs access to your code. But a variable of undeclared format can expand as change as required within your code. 
The general syntax for assigning a variable is: 
<prepropersition> <format> <scope> [name]<array index> <operator [value]> <extends [rootname]> 

prepropersition is optional and can be: 

    static - can not be changed once set (at either declaration or afterwards) 
    worm - (w)rite (o)nce (r)ead (m)any, unlike a static variable it's contents can be 
    reset with the wormreset() method. Variables can not be both static and worm. 
    unsigned - the following varible format is to be unsigned (default signed) 
If you do not give a prepropersition then it will be assumed that the variable being declared is both dynamic and signed. 
Note: prepropersition unsigned does not effect portable characters or strings. 
Examples: 

static string _myname="David Segal"; 
unsigned _somenumber=911; 
static _talkhost="Joan Williams"; 
static unsigned byte=255;

format is optional and can be: 

    byte - a byte 
    char - a single portable character 
    string - a portable character string 
    short - half length integer 
    int - integer 
    dint - double length integer 
    float -  an IEEE 754 floating point 
    dfloat - an IEEE 754 double length floating point 

A portable character is not nesserserly a byte, or any fixed unit in length. It is an opaque object from the program and may change depending on the language preferences on the user's decoder. Storing strings in these objects will guarentee they can be displayed by all users.

 Portable characters are also the default for keyboard interactions, and if matched by another portable character will also ensure international compatibility. 

You can not access a variable by its memory location, so there are no 'pointers' available in Uband. Instead if you wish to access only a portion of a string's contents use the .index variable method after its name. 

To create a diminsionalized variable declare it with it's length in square brackets, for example: 
unsigned byte _mybuffer[1024]; 
which creates a 1k block of unsigned bytes in the variable _mybuffer.  To access a one of these byte objects use _mybuffer[<0 to 1023>]. Use caution when declaring large arrays as user's may have set a limited variable space, which may be used up on declaring causing your uband application to close. 

scope is optional and can be any combination of: 
    local - (implied) the variable is only accessable within it's declared method 

    public - the variable is available anywhere that references it for read and writes 

    public.ro - it is available anywhere for read access but read/write within method 

    public.wo - it is available anywhere for write access but read/write within method 

    group - it is available for read/write access from group methods
 
    group.ro - it is available for read access from group methods but read/write within its local method 

    group.wo - it is available for write access from group methods but read/write within its local method 

    owner - it is available for read/write access from owner methods 

    owner.ro - it is available for read access from owner methods but read/write within its local method 

    owner.wo - it is available for write access from owner methods but read/write within its local method 

    auth - authenticate owner and group access (implies no public access) 

An owner method is any method which has been loaded from the same origin as the programs root. 
For example: 

If your method is stored at: 

http://server1.mysite.kom/billadams/program.uband 

Valid 'owner' methods can only loaded from http://server1.mysite.kom/billadams/ 
so, a method brought in from: 

http://server1.mysite.kom/billadams/billsbackup/music/tune1.uband 

would have 'owner' access to such a variable declared in a method from program.uband. However program.uband would not have owner access to a variable in tune1.uband. 
In the same way a method from: 

http://server1.mysite.kom/davidsegal/davesprogram.uband 
would not have owner access to any variable from the above locations.

Group methods can be loaded from any location, but must include a unique group id within the init() method or from the method that is referencing the group accessable variable. 
You can set up to 32 group id's from within each method plus another 128 from the init() (which are the only group id's which apply to every method).  Each will be searched for a match to the remote group accessable variable. If you need more group id's for more variables, break down your references into other methods and reference those using owner permissions. 

The use of group and owner clauses on their own do not offer any form of security for private information you do not want deceminated. They are intended so that programs with commonly named shared variables can be portable. For the storeage of secure information use the auth scope in addition to your owner and group access rights. Use only with important data however, as there is a performance penalty while authentication is sort and granted for such variables. For more information on securing your internal data see the section on 'Security'. 

Examples: 

public myvote=50; 
string public.ro owner myphonenumber=1800-989WALK; 
owner.ro auth Margo="Stage"; 
int group.wo owner temperature=33; 

name is required: 

Names of variables can include any of the standard letters and numbers including a selected number of punctuation. Names are case sensitive. You can include any character in a variables name except the following: 



.
period
*
multiply
/
divide
-
subtraction
,
comma
+
addition
\
back slash
=
equals
%
percentage
>
greater than
'
back quote
<
less than
`
single quote
:
colon
"
grouping quote
;
semi-colon
!
bang


A variable's name must be unique with the scope that it is defined. You may define a variable by the same name more than once, and no error will be generated, it's last definition being used. 

When accessing a variable from a different method the reference begins with it's method, for example: 

mydetails.name="Bob Edwards"; 
would asign "Bob Edwards" to the variable name within the method mydetails if it's scope allows it. 

Inherited variables can be set and read with the extends keyword given at the end of a variables assignment. The rootname is the variable's method/name that you wish to extend. 

You must have writable access rights to the rootname of the variable, or the extended variable name (if it already exists) in order to extend it. If the extension already exists it is overwritten for the duration of the new variables existance. For example: 
friend="Carl Castle" extends mydetails.name; 
Creates a new object in mydetails.name from any other method with rights as mydetails.name.friend, and setting it to "Carl Castle". 
Note: You can not simply supply a new name for a variable without assigning it a value or declaring it. So: 

name 

on it's own would not be a legal 'declaration' that name will be used as a variable in the following statements. If you do not wish to declare a variable's format or scope, there is no need to give the variable's name before it is used. 

operator is optional and can be: 
    = - (a single equals) asign value on right to variable name on left 

value is optional: 

 A value can be any data either supplied at the time of the statement such as: 
int somenumber=90; 
from another already defined variable: 
int somenumber=anothernumber; 
or as a result of a method or expression as in: 
int somenumber=factorize(8); 
int somenumber=(firstnumber>secondnumber); 
int somenumber=(firstnumber+1); 
If you declare the destinations variable such as in the above with the integersomenumber, then it's value must also be compatible with that format. Non compatible variables will end your program on error. See the table below to see inter-compatibility between variable types. 

right side variable format
can be asigned to
right side variable format
can be asigned to
byte
byte, short, int, dint, float, dfloat
float
float, dfloat
short
short, int, dint, float, dfloat
dfloat
dfloat
int
int, dint, float, dfloat
char
char, string
dint
dint, dfloat
string
string

When asigning variables that are declared unsigned from a signed source or visa versa there will be differences in the variable's values if the signed source is exceeded by half of the unsigned maximum storeage value. For example: 
unsigned byte yeoldenumber=255; 
byte ohno=yeoldenumber; 
In the above exchange ohno receives 255 from the unsigned yeoldenumber but because of its signed status ohno is read as -127. You can recover the value by redeclaring ohno: 
unsigned ohno; 
or by exchanging its value again with another unsigned variable: 
unisigned anothergasp; 
anothergasp=ohno; 
converting a variable's format 
In all situations asigning a variable of a 'higher' type to a lower one such as sending an int to a byte will cause an error unless you specifically convert during it's assignment. Conversion is done by putting the type of the 'lower' variable before the name of the 'higher' one, as in: 
unsigned byte smallnumber; 
int biggernumber=200; 
smallnumber=(byte) biggernumber; 
so smallnumber will get the value 200. But an unsigned byte can only hold values up to 255, so if you try and go over this, you only get 255 stored in smallnumber no matter what the value above that is in biggernumber. 
unsigned byte smallnumber; 
int toobignumber=300; 
smallnumber=(byte)toobignumber; 
window.print(smallnumber); 
will display 255 in the current window. But will not cause an error, which may be critical if you're not aware of the possibility of such a change in value within your program. Because of this, use variable conversions with care. 

arrays 

Sooner or later it becomes useful to have multiple instances of the same variable. You can use an array to access components of a variable using an integer from 0 to n, where n is the array member you are accessing. 

 There are no real limits to the number of members an array can have, the actual number though depends on user memory. You do not need to specify the total members of an array, or indeed that a variable is an array. However by not specifying array sizes you run the risk of your program reading beyond the size you have in mind. Such reads to undefined array locations will return a null value. Below you'll see some array declarations. 

int hotdogdays.index[10]; 
int morehotdogdays; 
hotdogday.index(0)=10, hotdogday.index(1)=2; 
morehotdogdays=20; 
morehotdogdays.index(20)=9;
 
You'll see that we use the method index(n) to assign a dimensionized value to a variable. The difference between hotdogdays and morehotdogdays is that hotdogdays is fixed to 10 such calendar dates (0 to 9), while morehotdogdays is allowed to expand dynamically. You can at a later point in the program however redefine hotdogdays into a dynamic form: 
int hotdogdays; 
and with no initializer the original data is kept, but it now becomes a dynamic array. In the same way, you can set limits to morehotdogdays: 

int morehotdogdays[10]; 
which limits it's maximum array member to 9 (array member 0 is first). However any previous data stored in members above 9 would be lost, even if we later made it dymanic again. 
Arrays always start from 0, if you require a negative based array you'll need to include the appropriate math as an argument to index(). It assumes below that temperature begins at a negative value which is increased beyond the resonable minimum (-100) and then divided by 10 to give an index value to an array of strings: 

window.print("The temperature today is %d degrees, which is %s\n". temperature, tempnames.index((temperature+100)/10)); 

(!): Don't get the array method confused with pos() which when applied to any variable reports the contents from that position. 
Pos() defaults to returning all data from that point, but you can specify any length to report. An example of the pos method is given below:
 
string titlename="Mr G.Renalds"; 
string nameonly=titlename.pos(3); 

which assigns G.Renalds to the string nameonly. As with the array method, pos begins with 0 as it's origin. You can mix these methods quite happily: 

string nameonly=manytitles.array(4).pos(3); 

so assigning nameonly from the manytitles array member 5 all data from character position 4. 
arrays with more than one dimension 

Multi-dimensional arrays are also handled in a similar way. You simply add the right number of comma seperated array values to the number of dimensions in your array when you declare it. The array method will take the other dimensions as arguments. You can have arrays up to 32 dimensions deep in total. So for a 3 dimensional array: 

int time_when_at_posisition[10,10,10]; 
... 
window.print("Location x=%d y=%d z=%d was reached at time reference %d\n", x, y, z, time_when_at_position.array(x,y,z)); 
parentage 

A variable can have many components that are all related to the primary object. These objects form the variable's type and are seperated with periods: 

color.red=20, color.green=40, color.blue=90; 

on the above information, the object color has 3 components, red, green and blue. If permission is granted by the creator of this variable then these components can be set and read. The object color contains all 3 sub components, so if another object was created called color2 with the same sub-components, transfering their contents can be done with a simple color=color2. 
Creating a new object can be simplified by using a constructor method. This consists of a method in the same name and root as the object with a "*" object being defined at the start of the method. 

int newcolor() { 
int *.blue=0, *.red=0, *.green=0; 

Notice that when you create a constructor for an object you must specify it's elemental variable formats. Just saying *.blue=0 isn't enough, the int is required here.You can then use this method newcolor as a new variable format in the same was as you would use int, float, string etc.. 
newcolor mycolor; 
mycolor.blue=50; 
Because newcolor initializes all objects with 0, mycolor.green and mycolor.red were zero'd when they were created. 

freeing up variables 

All variables take up some of the memory space that available to your program's data. Local variables that are only visable within a method are freed automatically when the method ends. 
Other variables exist and use portions of memory for the duration of the program, or until they are explictly freed by you. 
free(time_when_at_position); 
free(dom_of_allocation); 
free(has_value_at_the_expense_of_cost); 

 You can't be selective about freeing a variable.You can not free 'just a little' of it! If you have a multi-dimensionaized array, freeing it will free the whole thing. If you have a very long string you can't just free the last porition of it. In all of these cases, you could first move the data you want to keep to another variable, then free the old one. It's up to you to write for selective frees if you need them. Most of the time you wont, only on systems where memory is very low would there be any benefit to only freeing a portion of a variable. If you manage your storage, using public or global variables sparingly, there will be only a few cases that you'll need to use the free method. 
 
 

Objects 

Objects are everything, you already know the object window, which is assigned to the default user display. Using the new operator you can create your own objects from the primative types and use them with the standard methods.
 
new [primative object type] [new object name] 
primative object type is any already existing object from the system or your own program. Examples of primatives include window, keyboard and mouse. 
the new object name can not exist as method, variable or another object. Once successful you can use the new object name with methods that work with the primative type. 
new window lwin; 
lwin.print("hello!\n"); 
lwin.freshwindow(100,100,"My new window); 
lwin.print("hello again!\n"); 
lwin.close(); 

When first created the new object takes on the values of the primitive. So in the above example lwin when first used with the print method outputs to the default window. Next the newwindow method creates a new window and sets lwin to handle its output. You must be aware, that newwindow will overwrite any original window values stored in lwin and it is up to you to either transfer them or close the original window if it exists. As a matter of note, you cant say: 

window.freshwindow(... 
as all primatives are special in that they are assigned values on startup by the decoder and can not be overwritten afterwards. Therefore to use methods that create new instances you must first declare a new object to use with them: 
new window anotherwin.freshwindow(200,100,"pop up"); 
When a program closes all objects are cleaned up and closed, but it's good practice to close down your own objects. 
close() is the generic method that works with all system objects.
  
 
root object outlines 
window : The window object describes the associated input/ouput window, by default this will be the display space within the main decoders window. Use freshwindow(<width>, <height>, <title>) to open a new window. For hints on user's preferences for windows read in from the user object: user.prefwidth, user.prefheight and user.maxwidth, user.maxheight. Anything larger than the maxwidth and maxheight will be fixed back to those values. 

window - 
               internal window number 
               width width of this window object 
               height height of this window object 
               title title string of this window object 
               px mouse/pointer x position 
               py mouse/pointer y position 
               pbut mouse/pointer button 
               mode video mode 
               text* 

*sub-objects described below: 

text sub-object 
text.x location of cursor 
text.y location of cursor 
maximum values for these will be the width and height of the window. Drawing outside of these will not cause an error. 0,0 are always the origin co-ordinates.

text.foreground color of the text's foreground 
text.background color (if any) of that text's backgound (-1 = transparent) 
Colors are from the applications palette which propergates to all windows owned by the application.

text.sizewidth maximum horizontal size of a character 
text.sizeheight maximum height of a charater 
Text sizes are for the proportional charater, and give the actual size back in pixels. These values can be used as a guide when positioning text. For knowing the pixel sizes of strings use the text.getstringwidth(<string>) method. You can set your own widths and heights using the text.setsize(<width>, <height>) method. Note that not all size conbinations will be supported with a particular font. The system will find the nearest match and fill in its value into the text.sizewidth and text.sizeheight attributes.

text.font descriptive font name (sans, times etc..) 
Font names can only be set with the text.setfont(<fontname>) method, which will handle outcomes for fonts that are not available on the user's system. You can read this value in the normal way.

text.face face of the font (b-old, i-talic, u-nderline) 
Typeface can only be set with the text.setface(<face>) method. You can read the current values in the normal way with combinations of b, i and u giving the current face status.

text.spacing fixed or pro-portional character spacing 
Set this to fixed to force fixed spacing with a proporational font. A fixed width font uses the text.sizewidth and text.sizeheight for each character. Results are not perfect with all proportional fonts, so this should be used sparingly with descriptive font names other than 'system' which always can be assumed to be readable.


setting an object value would take the form: 
window.text.font.setfontbyname("sans"); 
window.text.font=1; 
window.text.foreground=15; 
window.text.background= -1; 
window.printf("hi there!\n"); 


user : The user object contains read only data describing the user's environment and any information about themselves which they have made available as public. 
user.version 
version is in the form major.minor.revision, for example 1.1.0 , 1.2.1. Version information is mostly intended to identify any known bugs in a decoder being used by a user. If your code is affected by these bugs you can determine that but checking this.

user.release 
release is in the form major.minor, for example 1.0, 1.2. Release information shows the decoder's level of features and support of utaho. See online development site for differences in the release number. It is intended that changes in the minor release will remain fully compatible within the same major number. While major changes will only be backwards compatible.

user.extensionsearch(<vendorname>, <extensionname>) 
extensions are add-ons provided by Tree or other 3rd party vendors. The vendorname is a unique string for the provider of the extension, you can search vendornames at the Em Channel website. The extensionname is vendor specific and if you'll using an extension you should consult the vendor for details of extensionnames and their meanings.


user.name 
User's name may or may not be given, and can be either only their first name, or their full name. Format of this string should not be relyed apon. Maximum length of the name string is 48 characters.

user.login 
If the user has an Em Channel account, their login will be available here. The maximum size of a login string is 24 characters.

user.handle 
A handle is the user's online public name over Em Channels, however the user may specify this name seperatly.

user.language 
Language takes the form of a pre-defined string a list of which can be got from the Em Channels developer site. Examples are 'ENGLISH' and "FRENCH'. In general no difference is made between varients of languages. Ie. the English used in Britain, in Austrailia etc...

user.contentpref[n..] 
Content preferences take the form of an array where each entry provides a 0 to 5 argument (0 being none accepted, 5 being any) to a standardized content type descriptor. Descriptors include 'ACTION',"NEWS',"VIOLENCE',"NUDITY' and others. For a full list of content types see Em Channels developer site. This argument also comes with the method user.contentcheck(<content type>,<rating>) which will automatically deal with content validation. The last member of the array is the one in which a null string is returned. If a user has left viewing controls un-set then this array will always return null.

user.emcontact 
A contact given here is the user's Em Channel 'call' contact, which if available can be used to send a message to the user over Em Channels.

user.country 
Country is a two letter standardized country code where the user resides. For a full list of country codes see the Em Channels developer site. Examples of this argument include: US, CA, FR, UK, JP..

user.email.work 
Email address for the user's work, maximum length is 127 characters. This is a single internet address with no spaces.

user.email.home 
Email address for the user's home, maximum length is 127 characters. This is a single internet address with no spaces.


user.tel.work 
Freeform user telephone number for their work location, maximum length is 32 characters. Number does not include any inter-country dialing information.

user.tel.home 
Freeform user telephone number for their home location, maximum length is 32 characters. Number does not include any inter-country dialing information.

user.fax.work 
Freeform user fax number for their work location, maximum length is 32 characters. Number does not include any inter-country dialing information.

user.fax.home 
Freeform user fax number for their home location, maximum length is 32 characters. Number does not include any inter-country dialing information.
 

uband conditionals 

There are a number of conditionals, flow control or 'decision' statements in uband. They are modeled after traditional types such as 'for' and 'while'. For more information and examples, click on the condition's name. 
Uband when considering arguments directly such as _a<10 will provide 0 (zero) if true or -1 (minus one) if false. You can write: 
int _test=(15<10); 
and the variable _test will then have the value -1. 
When writing your own methods that are considered for arugments to conditional statements you may return any value of 0 and above for ture, and any below 0 for false. Use caution when returning strings, as returning a non numeric (such as 'house') will always be true, but a string value will be considered as a numberic so returning the string '-201' would give a false. 
Returning a 'bytes' value will always be true, returning no variable or a null string will always be true. Methods that do not return a value will also always be considered true. 


while 
while( <some condition is true>)  { 
     $$ execute these statements 
    } 
The while condition will first check that it's argument is true (ie. 0 or higher) and then proceed to execute the bracketed statements. At the end of the statements it will test the argument again. When false execution continues after the bracketed statements. 

for 
for( <some condition is true>; <after first loop statements> )  // 
for( <set up statment(s)> ; <some condition is true>; <after first loop statements> )  { 
     $$ execute these statements 
    } 
The for condition tests an argument to be true (ie. 0 or higher) 



Events
 
Uband Event Programming Interface 
The realtime event methods for Uband applications.
 

Disabling all events 
<number of events cleared> event.clearall() 

Disables all events that have been previously defined. 

Returns: 
int : number of events cleared 

Disabling events by type 
<number of events cleared> event.clear(<event type>)



Disables all events of specified type. 
Returns: 
int : number of events cleared 


Disabling events by method 
<number of events cleared> event.clearmethod(<method>)



Disables all events that use the specified method. Any events of the same event type using other methods continue to exist. Method is determined to be unique by its name and the type and number of calling varibles. 
Returns: 
int : number of events cleared 

Enabling an event 
event(<event type>, <method>, <singular>)

This is the main method for the capture of events. 
You may need to first program some of the event.catch varibles to use the events. Values will remain in the event.catch structure for the next call. See idividual event types for the varibles used. 

int event.catch.x (x position / x start position) 
int event.catch.y (y position / y start position) 
int event.catch.width (x length) 
int event.catch.height (y length) 
char event.catch.data (64 byte buffer) 

Singular will first cancel any events that are currently attached to the Event Type of the new event. This ensures only one method will be called apon receiving an event, otherwise each attached method will be called in the order they were attached. If difining a multiple Event Type for an event, Singular will clear each of the Event Type's components in turn. 
Event type is defined from any combination of the OR'd bitmaps below:
Event type
Description
Setup varibles
Return varibles
Notes

EV_MOUSEDN
Mouse button pressed
x, y = optional area start 
width, height = optional area size
x, y = where mouse button was pressed
define x=-1, y=-1 to pick up button presses anywhere

EV_MOUSEUP
Mouse button released
x, y = optional area start 
width, height = optional area size
x, y = where mouse button was released
define x=-1, y=-1 to pick up button releases anywhere

EV_MOUSEDC
Mouse button double clicked within the predefined time of UBAND.

MOUSEDOUBLECLICKTIME
x, y = optional area start 
width, height = optional area size
x, y = where mouse button was double clicked
define x=-1, y=-1 to pick up double clicks anywhere

EV_MOUSEIN
Mouse enterted area
x, y = area origin 
width, height = size
x, y = where mouse entered

EV_MOUSEOUT
Mouse exited area
x, y = area origin 
width, height = size
x, y = where mouse exited

 
EV_MOUSECLICK
Mouse button press followed by a release with the predefined time of UBAND.MOUSECLICKTIME
x, y = optional area start 
width, height = optional area size
x, y = where mouse button was clicked
define x=-1, y=-1 to pick up mouse clicks anywhere
RESERVED WORDS
 
UBand Reserved Words 
These are words that you can not use for your own varibles or methods. All are case sensitive. Eg. Byte="me"; is legal while byte="you"; is not. 
byte 
char 
dfloat 
dinteger 
float 
integer 
static 
string 
unsigned 

Operators 
=    asign value to 
==  test equality 
>    test left side is greater than right side 
<    test left side is lower than right side 
=>  test left side is equal to or greater than right side 
=<  test left side is equal to or lower than right side 
*    multiply 
+    addition of numbers of string characters 
-    subtraction 
/    divide 
% percentage (eg. 10%50 would give 5) 
" "  quoted string 
' '  alternative quoted string 
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